#@ load("openapi.lib.yml", "response", "reference", "type", "array")

openapi: 3.0.1
security: []
info:
  title: Qdrant API
  description: >

    API description for Qdrant vector search engine.


    This document describes CRUD and search operations on collections of points (vectors with payload).


    Qdrant supports any combinations of `should`, `must` and `must_not` conditions,
    which makes it possible to use in applications when object could not be described solely by vector.
    It could be location features, availability flags, and other custom properties businesses should take into account.

    ## Examples

    This examples cover the most basic use-cases - collection creation and basic vector search.

    ### Create collection

    First - let's create a collection with dot-production metric.

    ```

    curl -X PUT 'http://localhost:6333/collections/test_collection' \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "vectors": {
          "size": 4,
          "distance": "Dot"
        }
      }'

    ```

    Expected response:

    ```

    {
        "result": true,
        "status": "ok",
        "time": 0.031095451
    }

    ```

    We can ensure that collection was created:

    ```

    curl 'http://localhost:6333/collections/test_collection'

    ```

    Expected response:

    ```

    {
      "result": {
        "status": "green",
        "vectors_count": 0,
        "segments_count": 5,
        "disk_data_size": 0,
        "ram_data_size": 0,
        "config": {
          "params": {
            "vectors": {
              "size": 4,
              "distance": "Dot"
            }
          },
          "hnsw_config": {
            "m": 16,
            "ef_construct": 100,
            "full_scan_threshold": 10000
          },
          "optimizer_config": {
            "deleted_threshold": 0.2,
            "vacuum_min_vector_number": 1000,
            "max_segment_number": 5,
            "memmap_threshold": 50000,
            "indexing_threshold": 20000,
            "flush_interval_sec": 1
          },
          "wal_config": {
            "wal_capacity_mb": 32,
            "wal_segments_ahead": 0
          }
        }
      },
      "status": "ok",
      "time": 2.1199e-05
    }

    ```


    ### Add points

    Let's now add vectors with some payload:

    ```

    curl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
      "points": [
        {"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": "Berlin"}},
        {"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": ["Berlin", "London"] }},
        {"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": ["Berlin", "Moscow"] }},
        {"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": ["London", "Moscow"] }},
        {"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": [0]}},
        {"id": 6, "vector": [0.35, 0.08, 0.11, 0.44]}
      ]
    }'

    ```

    Expected response:

    ```

    {
        "result": {
            "operation_id": 0,
            "status": "completed"
        },
        "status": "ok",
        "time": 0.000206061
    }

    ```

    ### Search with filtering

    Let's start with a basic request:

    ```

    curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "vector": [0.2,0.1,0.9,0.7],
        "top": 3
    }'

    ```

    Expected response:

    ```

    {
        "result": [
            { "id": 4, "score": 1.362, "payload": null, "version": 0 },
            { "id": 1, "score": 1.273, "payload": null, "version": 0 },
            { "id": 3, "score": 1.208, "payload": null, "version": 0 }
        ],
        "status": "ok",
        "time": 0.000055785
    }

    ```

    But result is different if we add a filter:

    ```

    curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "filter": {
            "should": [
                {
                    "key": "city",
                    "match": {
                        "value": "London"
                    }
                }
            ]
        },
        "vector": [0.2, 0.1, 0.9, 0.7],
        "top": 3
    }'

    ```

    Expected response:

    ```

    {
        "result": [
            { "id": 4, "score": 1.362, "payload": null, "version": 0 },
            { "id": 2, "score": 0.871, "payload": null, "version": 0 }
        ],
        "status": "ok",
        "time": 0.000093972
    }

    ```

  contact:
    email: andrey@vasnetsov.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: master
externalDocs:
  description: Find out more about Qdrant applications and demo
  url: https://qdrant.tech/documentation/
servers:
  - url: "{protocol}://{hostname}:{port}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      hostname:
        default: localhost
      port:
        default: "6333"
tags:
  - name: collections
    description: Searchable collections of points.
  - name: points
    description: Float-point vectors with payload.
  - name: cluster
    description: Service distributed setup
  - name: snapshots
    description: Storage and collections snapshots

paths:

  /collections/{collection_name}/points/scroll:
    post:
      tags:
        - points
      summary: Scroll points
      description: Scroll request - paginate over all points which matches given filtering condition
      operationId: scroll_points
      requestBody:
        description: Pagination and filter parameters
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScrollRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to retrieve from
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(reference("ScrollResult"))

  /collections/{collection_name}/points/search:
    post:
      tags:
        - points
      summary: Search points
      description: Retrieve closest points based on vector similarity and given filtering conditions
      operationId: search_points
      requestBody:
        description: Search request with optional filtering
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(array(reference("ScoredPoint")))

  /collections/{collection_name}/points/search/batch:
    post:
      tags:
        - points
      summary: Search batch points
      description: Retrieve by batch the closest points based on vector similarity and given filtering conditions
      operationId: search_batch_points
      requestBody:
        description: Search batch request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequestBatch"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(array(array(reference("ScoredPoint"))))

  /collections/{collection_name}/points/search/groups:
    post:
      tags:
        - points
      summary: Search point groups
      description: Retrieve closest points based on vector similarity and given filtering conditions, grouped by a given payload field
      operationId: search_point_groups
      requestBody:
        description: Search request with optional filtering, grouped by a given payload field
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchGroupsRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(reference("GroupsResult"))

  /collections/{collection_name}/points/recommend:
    post:
      tags:
        - points
      summary: Recommend points
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
      operationId: recommend_points
      requestBody:
        description: Request points based on positive and negative examples.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(array(reference("ScoredPoint")))

  /collections/{collection_name}/points/recommend/batch:
    post:
      tags:
        - points
      summary: Recommend batch points
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
      operationId: recommend_batch_points
      requestBody:
        description: Request points based on positive and negative examples.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendRequestBatch"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(array(array(reference("ScoredPoint"))))

  /collections/{collection_name}/points/recommend/groups:
    post:
      tags:
        - points
      summary: Recommend point groups
      description: Look for the points which are closer to stored positive examples and at the same time further to negative examples, grouped by a given payload field.
      operationId: recommend_point_groups
      requestBody:
        description: Request points based on positive and negative examples, grouped by a payload field.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendGroupsRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to search in
          required: true
          schema:
            type: string
        - name: consistency
          in: query
          description: Define read consistency guarantees for the operation
          required: false
          schema:
            $ref: "#/components/schemas/ReadConsistency"
      responses: #@ response(reference("GroupsResult"))

  /collections/{collection_name}/points/count:
    post:
      tags:
        - points
      summary: Count points
      description: Count points which matches given filtering condition
      operationId: count_points
      requestBody:
        description: Request counts of points which matches given filtering condition
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CountRequest"

      parameters:
        - name: collection_name
          in: path
          description: Name of the collection to count in
          required: true
          schema:
            type: string
      responses: #@ response(reference("CountResult"))

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        time:
          type: number
          format: float
          description: Time spent to process this request
        status:
          type: object
          properties:
            error:
              type: string
              description: Description of the occurred error.
        result:
          type: object
          nullable: true

